home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3c / gettxt.z / gettxt
Encoding:
Text File  |  2002-10-03  |  8.1 KB  |  136 lines
  1.  
  2.  
  3.  
  4. ggggeeeettttttttxxxxtttt((((3333CCCC))))                                                          ggggeeeettttttttxxxxtttt((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _gggg_eeee_tttt_tttt_xxxx_tttt - retrieve a text string
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_uuuu_nnnn_iiii_ssss_tttt_dddd_...._hhhh_>>>>
  13.  
  14.      _cccc_hhhh_aaaa_rrrr _****_gggg_eeee_tttt_tttt_xxxx_tttt _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_m_s_g_i_d_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_d_f_l_t__s_t_r_))))_;;;;
  15.  
  16. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  17.      _gggg_eeee_tttt_tttt_xxxx_tttt retrieves a text string from a message file.  The arguments to the
  18.      function are a message identification _m_s_g_i_d and a default string _d_f_l_t__s_t_r
  19.      to be used if the retrieval fails.
  20.  
  21.      The text strings are in files created by the _mmmm_kkkk_mmmm_ssss_gggg_ssss utility [see
  22.      _mmmm_kkkk_mmmm_ssss_gggg_ssss(1)] and installed in directories in
  23.      _////_uuuu_ssss_rrrr_////_llll_iiii_bbbb_////_llll_oooo_cccc_aaaa_llll_eeee_////_l_o_c_a_l_e_////_LLLL_CCCC______MMMM_EEEE_SSSS_SSSS_AAAA_GGGG_EEEE_SSSS.
  24.  
  25.      The directory _l_o_c_a_l_e can be viewed as the language in which the text
  26.      strings are written.  The user can request that messages be displayed in
  27.      a specific language by setting environment variables.  That is, the
  28.      _l_o_c_a_l_e directory searched is specified by the _LLLL_CCCC______MMMM_EEEE_SSSS_SSSS_AAAA_GGGG_EEEE_SSSS environment
  29.      variable if it is set to a non-empty value.  Otherwise, it is specified
  30.      by the _LLLL_AAAA_NNNN_GGGG environment variable if it is set to a non-empty value.
  31.      Otherwise, the directory _CCCC is used.
  32.  
  33.      The user can also change the language in which the messages are displayed
  34.      by invoking the _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee function with the appropriate arguments.  If
  35.      the locale is explicitly changed (via _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee), the pointers returned
  36.      by _gggg_eeee_tttt_tttt_xxxx_tttt may no longer be valid.
  37.  
  38.      The following depicts the acceptable syntax of _m_s_g_i_d for a call to
  39.      _gggg_eeee_tttt_tttt_xxxx_tttt.
  40.  
  41.           _[[[[_m_s_g_f_i_l_e_n_a_m_e_]]]]_::::_m_s_g_n_u_m_b_e_r
  42.  
  43.      _m_s_g_f_i_l_e_n_a_m_e indicates the message database that contains the localized
  44.      version of the text string.  _m_s_g_f_i_l_e_n_a_m_e must be limited to 14
  45.      characters.  These characters must be selected from a set of all
  46.      characters values, excluding _\\\\_0000 (null) and the ASCII codes for _//// (slash)
  47.      and _:::: (colon).
  48.  
  49.      _m_s_g_n_u_m must be a positive number that indicates the index of the string
  50.      in the message database.
  51.  
  52.      If _m_s_g_f_i_l_e_n_a_m_e does not exist in the locale (specified by the last call
  53.      to _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee using the _LLLL_CCCC______AAAA_LLLL_LLLL or _LLLL_CCCC______MMMM_EEEE_SSSS_SSSS_AAAA_GGGG_EEEE_SSSS categories), or if the
  54.      message number is out of bounds, _gggg_eeee_tttt_tttt_xxxx_tttt attempts to retrieve the message
  55.      from the C locale.  If this second retrieval fails, _gggg_eeee_tttt_tttt_xxxx_tttt uses _d_f_l_t__s_t_r.
  56.  
  57.      If _m_s_g_f_i_l_e_n_a_m_e is omitted, _gggg_eeee_tttt_tttt_xxxx_tttt attempts to retrieve the string from
  58.      the default catalog specified by the last call to _ssss_eeee_tttt_cccc_aaaa_tttt(3C).
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ggggeeeettttttttxxxxtttt((((3333CCCC))))                                                          ggggeeeettttttttxxxxtttt((((3333CCCC))))
  71.  
  72.  
  73.  
  74.      _gggg_eeee_tttt_tttt_xxxx_tttt outputs _MMMM_eeee_ssss_ssss_aaaa_gggg_eeee _nnnn_oooo_tttt _ffff_oooo_uuuu_nnnn_dddd_!!!!_!!!!_\\\\_nnnn if:
  75.           - _m_s_g_f_i_l_e_n_a_m_e is not a valid catalog name as defined above
  76.           - no catalog is specified (either explicitly or via _ssss_eeee_tttt_cccc_aaaa_tttt)
  77.           - _m_s_g_n_u_m_b_e_r is not a positive number
  78.           - no message could be retrieved and _d_f_l_t__s_t_r was omitted
  79.  
  80. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  81.      In the following code fragment, _tttt_eeee_ssss_tttt is the name of the file that
  82.      contains the messages and _1111_0000 is the message number.
  83.  
  84.           _gggg_eeee_tttt_tttt_xxxx_tttt_((((_""""_tttt_eeee_ssss_tttt_::::_1111_0000_""""_,,,, _""""_hhhh_eeee_llll_llll_oooo _wwww_oooo_rrrr_llll_dddd_\\\\_nnnn_""""_))))
  85.           _gggg_eeee_tttt_tttt_xxxx_tttt_((((_""""_tttt_eeee_ssss_tttt_::::_1111_0000_""""_,,,, _""""_""""_))))
  86.           _ssss_eeee_tttt_cccc_aaaa_tttt_((((_""""_tttt_eeee_ssss_tttt_""""_))))_;;;;
  87.           _gggg_eeee_tttt_tttt_xxxx_tttt_((((_""""_::::_1111_0000_""""_,,,, _""""_hhhh_eeee_llll_llll_oooo _wwww_oooo_rrrr_llll_dddd_\\\\_nnnn_""""_))))
  88.  
  89. FFFFIIIILLLLEEEESSSS
  90.      The following files are created by _mmmm_kkkk_mmmm_ssss_gggg_ssss:
  91.                                                 default message files
  92.          _////_uuuu_ssss_rrrr_////_llll_iiii_bbbb_////_llll_oooo_cccc_aaaa_llll_eeee_////_CCCC_////_LLLL_CCCC______MMMM_EEEE_SSSS_SSSS_AAAA_GGGG_EEEE_SSSS_////_****
  93.                                                 message files for language
  94.                                                 specified by _l_o_c_a_l_e
  95.          _////_uuuu_ssss_rrrr_////_llll_iiii_bbbb_////_llll_oooo_cccc_aaaa_llll_eeee_////_l_o_c_a_l_e_////_LLLL_CCCC______MMMM_EEEE_SSSS_SSSS_AAAA_GGGG_EEEE_SSSS_////_****
  96.  
  97.  
  98. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  99.      _eeee_xxxx_ssss_tttt_rrrr(1), _gggg_eeee_tttt_tttt_xxxx_tttt(1), _mmmm_kkkk_mmmm_ssss_gggg_ssss(1), _ssss_rrrr_cccc_hhhh_tttt_xxxx_tttt(1), _llll_ffff_mmmm_tttt(3C), _pppp_ffff_mmmm_tttt(3C),
  100.      _ssss_eeee_tttt_cccc_aaaa_tttt(3C), _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee(3C), _eeee_nnnn_vvvv_iiii_rrrr_oooo_nnnn(5)
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.                                                                         PPPPaaaaggggeeee 2222
  133.  
  134.  
  135.  
  136.